OpenEdge Development:<br />ProDataSets ROW-STATE attribute

There is a ROW-STATE attribute on the temp-table buffer in both the after-table and the before-table to allow you to determine how, if at all, each record has been changed. ROW-STATE is an integer value representing one of these constants, which you can and should use to identify the meaning of the ROW-STATE:

0=ROW-UNMODIFIED

1=ROW-DELETED

2=ROW-MODIFIED

3=ROW-CREATED

Note that these are unquoted literals that correspond to integer values, much like the values NO-LOCK, SHARE-LOCK, and EXCLUSIVE-LOCK for LOCK-MODE. You use the literals in 4GL logic, in statements such as this:

IF hTTCust:ROW-STATE = ROW-MODIFIED THEN…

Each record in the after-table that has been modified or added has an internal pointer to its counterpart in the before-table. These after-table records have a ROW-STATE value of ROW-MODIFIED or ROW-CREATED, depending on whether the row has been added to the temp-table since TRACKING-CHANGES was set to true. Deleted records do not appear in the after-table, because it reflects the current state of the data. Records in the after-table that have not been added or changed have a ROW-STATE of ROW-UNMODIFIED. These records have no counterpart in the before-table.

Every record in the before-table has a nonzero ROW-STATE because every record is the before-image for a deleted, created, or modified record. Records in the before-table can have a ROW-STATE equal to one of these values:

ROW-DELETED — A deleted row in the before-table holds the original field values of the record at the time TRACKING-CHANGES was set to true. It has no counterpart in the after-table. A record is moved from the after-table to the before-table when it is deleted. Thus, the only way to locate deleted records is in the before-table. If a record is modified and then later deleted before changes are processed, then its state is ROW-DELETED and there is no record of the changes made before that.

ROW-MODIFIED — A modified row in the before-table holds the field values of the record at the time that TRACKING-CHANGES was last set to true. The row is copied from the after-table when it is first changed. No intermediate changes between the “original” values and the latest values are saved anywhere.

ROW-CREATED — A newly created row is created in the before-table at the same time that the equivalent record is created in the after-table. The before-table row for a created row does not hold any meaningful field values. It serves merely as a placeholder for the row so that you can identify created rows along with modified and deleted ones by looking at the before-table. The field values in the after-table can then be changed as the record is edited, just as for changed rows. The ROW-STATE remains ROW-CREATED until changes to the table have been processed, regardless of how many times field values have been modified in the meantime.

Records in the after-table can have a ROW-STATE of ROW-UNMODIFIED, ROW-CREATED, or ROW-MODIFIED. This means that new records and changed records can be tracked through either table. However, because deleted records are removed from the after-table, they can be tracked only through the before-table. In general, you should process changes through the before-table for this reason.

ROW-STATE function

It is not possible to check the value of an attribute such as ROW-STATE in a where-clause. For this reason, there is also a ROW-STATE function that can be referenced in a where-clause to let you filter ProDataSet temp-table rows by their ROW-STATE. The ROW-STATE function takes a buffer name as its argument and returns the same integer value as the ROW-STATE attribute. Ordinarily you should apply the function to a before-table buffer, but you can also use the after-table buffer name as well with the same effect. If there is no record in the buffer passed, or it is not a before-table, or is not an after-table that has a before-table associated with it, then the ROW-STATE value returned is “?”. An error is not raised.

The function lets you construct a where-clause, such as in the following example:


`FOR EACH` <before-table-buf> `WHERE` `ROW-STATE`(<before-table-buf>) = ROW-MODIFIED: ..... END.

Special restrictions on TRACKING-CHANGES

There are some general restrictions on the use of TRACKING-CHANGES that mostly exist as sanity checks to prevent people from doing unexpected things and expecting something useful to happen:

If you try to do a FILL or an EMPTY-DATASET while TRACKING-CHANGES is true, Progress raises an error.

If you pass a ProDataSet remotely or locally by value and TRACKING-CHANGES is true for the ProDataSet or any of its tables, the before- and after-tables are passed in their current state, but the value of the TRACKING-CHANGES attribute is not passed, that is, it is not automatically set to TRUE on the receiving side.

Normally, if you set TRACKING-CHANGES to TRUE, make changes, and then pass the ProDataSet as a parameter, the receiver processes the changes without making further changes that should be recorded in the before-table. If the receiving procedure wants to make further changes, it must set TRACKING-CHANGES to true after receiving the ProDataSet parameter.